<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>Building the NumPy API and reference docs &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="NumPy’s Documentation" href="index.html" >
    <link rel="next" title="Release Notes" href="../release.html" >
    <link rel="prev" title="A Guide to NumPy/SciPy Documentation" href="howto_document.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" accesskey="U">NumPy’s Documentation</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="../release.html" title="Release Notes"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="howto_document.html" title="A Guide to NumPy/SciPy Documentation"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Building the NumPy API and reference docs</a><ul>
<li><a class="reference internal" href="#instructions">Instructions</a></li>
<li><a class="reference internal" href="#sphinx-extensions">Sphinx extensions</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="howto_document.html"
                        title="previous chapter">A Guide to NumPy/SciPy Documentation</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="../release.html"
                        title="next chapter">Release Notes</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="building-the-numpy-api-and-reference-docs">
<span id="howto-build-docs"></span><h1>Building the NumPy API and reference docs<a class="headerlink" href="#building-the-numpy-api-and-reference-docs" title="Permalink to this headline">¶</a></h1>
<p>We currently use <a class="reference external" href="http://www.sphinx-doc.org/">Sphinx</a> for generating the API and reference
documentation for NumPy.  You will need Sphinx 1.8.3 &lt;= 1.8.5.</p>
<p>If you only want to get the documentation, note that pre-built
versions can be found at</p>
<blockquote>
<div><p><a class="reference external" href="https://docs.scipy.org/">https://docs.scipy.org/</a></p>
</div></blockquote>
<p>in several different formats.</p>
<div class="section" id="instructions">
<h2>Instructions<a class="headerlink" href="#instructions" title="Permalink to this headline">¶</a></h2>
<p>If you obtained NumPy via git, get also the git submodules that contain
additional parts required for building the documentation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">submodule</span> <span class="n">init</span>
<span class="n">git</span> <span class="n">submodule</span> <span class="n">update</span>
</pre></div>
</div>
<p>In addition, building the documentation requires the Sphinx extension
<em class="xref py py-obj">plot_directive</em>, which is shipped with <a class="reference external" href="https://matplotlib.org/">Matplotlib</a>. This Sphinx extension can
be installed by installing Matplotlib. You will also need python3.6.</p>
<p>Since large parts of the main documentation are obtained from numpy via
<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">numpy</span></code> and examining the docstrings, you will need to first build
NumPy, and install it so that the correct version is imported.</p>
<p>Note that you can eg. install NumPy to a temporary location and set
the PYTHONPATH environment variable appropriately.</p>
<p>After NumPy is installed, install SciPy since some of the plots in the random
module require <a class="reference external" href="https://docs.scipy.org/doc/scipy/reference/special.html#module-scipy.special" title="(in SciPy v1.4.1)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">scipy.special</span></code></a> to display properly. Now you are ready to
generate the docs, so write:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>in the <code class="docutils literal notranslate"><span class="pre">doc/</span></code> directory. If all goes well, this will generate a
<code class="docutils literal notranslate"><span class="pre">build/html</span></code> subdirectory containing the built documentation. If you get
a message about <code class="docutils literal notranslate"><span class="pre">installed</span> <span class="pre">numpy</span> <span class="pre">!=</span> <span class="pre">current</span> <span class="pre">repo</span> <span class="pre">git</span> <span class="pre">version</span></code>, you must
either override the check by setting <code class="docutils literal notranslate"><span class="pre">GITVER</span></code> or re-install NumPy.</p>
<p>Note that building the documentation on Windows is currently not actively
supported, though it should be possible. (See <a class="reference external" href="http://www.sphinx-doc.org/">Sphinx</a> documentation
for more information.)</p>
<p>To build the PDF documentation, do instead:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">latex</span>
<span class="n">make</span> <span class="o">-</span><span class="n">C</span> <span class="n">build</span><span class="o">/</span><span class="n">latex</span> <span class="nb">all</span><span class="o">-</span><span class="n">pdf</span>
</pre></div>
</div>
<p>You will need to have Latex installed for this.</p>
<p>Instead of the above, you can also do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">dist</span>
</pre></div>
</div>
<p>which will rebuild NumPy, install it to a temporary location, and
build the documentation in all formats. This will most likely again
only work on Unix platforms.</p>
<p>The documentation for NumPy distributed at <a class="reference external" href="https://docs.scipy.org">https://docs.scipy.org</a> in html and
pdf format is also built with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">dist</span></code>.  See <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_RELEASE.rst.txt">HOWTO RELEASE</a> for details on
how to update <a class="reference external" href="https://docs.scipy.org">https://docs.scipy.org</a>.</p>
</div>
<div class="section" id="sphinx-extensions">
<h2>Sphinx extensions<a class="headerlink" href="#sphinx-extensions" title="Permalink to this headline">¶</a></h2>
<p>NumPy’s documentation uses several custom extensions to Sphinx.  These
are shipped in the <code class="docutils literal notranslate"><span class="pre">sphinxext/</span></code> directory (as git submodules, as discussed
above), and are automatically enabled when building NumPy’s documentation.</p>
<p>If you want to make use of these extensions in third-party
projects, they are available on <a class="reference external" href="https://pypi.org/">PyPi</a> as the <a class="reference external" href="https://python.org/pypi/numpydoc">numpydoc</a> package.</p>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>